home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / wp / isamf411.zip / ISAMFIND.DOC < prev    next >
Text File  |  1994-11-21  |  20KB  |  390 lines
  1. ISAMFIND.DOC
  2. 11/21/94
  3.  
  4. Program written by:
  5.                         Bruce Guthrie
  6.                         Room H-4885
  7.                         U.S. Dept of Commerce/ESA/OBA/BSISD
  8.                         Washington, D.C. 20230
  9.  
  10.                         (202) 482-3234
  11.  
  12. You may freely copy and re-distribute this program; however, the U.S.
  13. Department of Commerce neither guarantees nor assures compatibility of the
  14. program with all computer software or hardware.
  15.  
  16. Foreign users:  Please provide an Internet e-mail address in all correspondence
  17. or and just e-mail your problems to me at bgu@cu.nih.gov
  18.  
  19.  
  20. The ISAMFIND.EXE program takes an ISAM word-index created by the ISAMMAKE.EXE
  21. program and searches it for you.  If the word(s) you specify are found in the
  22. data base, the program will typically list the files for you and then try to
  23. view them using the READ program (or any other text-file viewer).
  24.  
  25. Definition of "word":  Currently, the program defines a "word" as consisting
  26. only of letters of the alphabet.  By default, non-letters are treated as word
  27. delimiters (you can override this with the /ACCEPT=string parameter).  Words are
  28. a minimum of three characters in length (can be changed to be from 2 to 5) and a
  29. maximum of 10.
  30.  
  31.  
  32. Features (of ISAMMAKE and ISAMFIND combination):
  33.   * Programs allow basically an unlimited number of files to be indexed.
  34.   * For primarily text documents, index is roughly the size of all the original
  35.     text files combined.
  36.   * Non-text documents can be scanned but, obviously, not many words will be
  37.     found in them.
  38.   * Documents are retrieved based on a "best match" formula which returns first
  39.     those documents which have a higher proportion of hits relative to their
  40.     size.
  41.   * Can count words in the document title higher than words within the text of
  42.     the document.
  43.   * Can specify what characters constitute a word (/ACCEPT=string parm).
  44.   * Can specify 8-character "file areas" for each file and restrict the search
  45.     based on these file areas.
  46.   * Can retrieve based on date so only the newer documents are retrieved.
  47.   * Can incrementally update the data bases with just newly modified files.
  48.   * Can either view the resulting files on the screen or write out a file which
  49.     contains the file names that matched the request.
  50.   * Output format is configurable.
  51.   * Can specify exclusion words that will be skipped when with the user enters
  52.     words to search for.
  53.   * Ideal tool for a help desk which has a lot of information to search through.
  54.  
  55.  
  56.  
  57. Since ISAMMAKE.EXE and ISAMFIND.EXE are related and share some of the same
  58. options, there are some common features that are documented in the documentation
  59. for one of the routines and not the other.  In general, most of the shared
  60. documentation ends up in ISAMFIND.DOC since that's all that people need to
  61. search the documents.  Shared documentation is as follows:
  62.  
  63.         Features                        see ISAMFIND.DOC documentation
  64.         The ISAMFIND.INI file           see ISAMFIND.DOC documentation
  65.         Format statements               see ISAMFIND.DOC documentation
  66.         Quick demo                      see ISAMMAKE.DOC documentation
  67.  
  68.  
  69. Scoring mechanism:
  70.  
  71. The ISAMFIND program presents your documents to you based on a "best document"
  72. score.  The score is based on looking at the number of times your particular
  73. word appears in the document and dividing the result by the number of words in
  74. the document.  The result is then multiplied by 1000.  The documents which rise
  75. to the top of the list will be those documents where the word frequency is
  76. proportional higher than it is in other documents.
  77.  
  78. For example, let's look at three of the test documents referenced in the
  79. ISAMDEMO.LST demo file:
  80.  
  81. ISAMDEMO.001 Cat Story
  82.       The cat and the dog came back and danced long.
  83. ISAMDEMO.002 Dog Story
  84.       The dog was in house.
  85. ISAMDEMO.003 House story
  86.       The house was four stories high and pretty darn big.
  87.  
  88. There are 5 words in the second document, 10 in the other two.  The word "the"
  89. appears in all three documents.  In the first document, it appears twice and
  90. once in the other two documents.  Since the score is based on the word frequency
  91. divided by the total number of words (multiplied by 1000), "the" rates scores of
  92. 200 (2/10*1000), 200 (1/5*1000), and 100 (1/10*1000) in each of the documents.
  93. The first and second documents will appear in the listing before the third one
  94. does.
  95.  
  96. In the case of wildcarded words (so "THE" would find "THESE" and "THEM" as well
  97. as "THE"), scores are added together.
  98.  
  99. In cases of multiple words in a string search, the scores are again added
  100. together but a single document is required to have all words in order to show
  101. up.
  102.  
  103. In addition to the words of the text, the words which appear in the title of a
  104. document ("Cat Story", "Dog Story", and "House story" in our case) are also
  105. considered in the search.  Words in the title are typically considered more
  106. important than words in the text; you can assign a higher weight to the title
  107. words when the index is created by the ISAMMAKE program but the default
  108. weighting is three; words in the title are three times as important to your
  109. weights as words in the text.  In addition, words in the title do not count in
  110. the document's word count at all.
  111.  
  112.  
  113. In our case, a search request of "dog" would result in scores of 100
  114. (1/10*1000), 400 ((1*3)+1/10*1000), and 0 (0/10*1000) for our three documents.
  115.  
  116. The program, by default, presumes that search words should begin with the
  117. characters specified but may include additional characters.  Thus, "THE" will
  118. find "THESE" and "THEM".  You can override this by using the /TRUNC parameter.
  119. Even if the /TRUNC parameter is specified, you can ask for non-truncated
  120. searching on a word-by-word basis; "DOG* STORY /TRUNC" will find either "DOG" or
  121. "DOGS".
  122.  
  123.  
  124. The ISAMFIND.INI file:
  125.  
  126. ISAMFIND will read a ISAMFIND.INI file if one is found.  (You can specify a
  127. different file name if desired.) (Note that ISAMFIND and ISAMMAKE both, by
  128. default, share the same INI file; options which are valid in one routine but not
  129. in the other are ignored by the non-supporting routine.)
  130.  
  131. The file is an ASCII text file that can be created maintained by hand.  The file
  132. can consist or one or more command line parameters (only those that begin with a
  133. "/"), one statement per line.  The file can also contain the input format
  134. ("FI=") and output format ("FO=") statements; note that these commands cannot
  135. be passed in from the command line so you will typically need an initialization
  136. file.
  137.  
  138. The file can also contain comments which are blank lines or any line beginning
  139. with:
  140.         ;    (semi-colon)
  141.         :    (colon)
  142.         '    (quote)
  143.  
  144. ISAMFIND looks for the initialization file in your default subdirectory first.
  145. It then searches for it in the subdirectory where the executable was and then
  146. goes through your DOS path.
  147.  
  148. Passing in "/-I" or "/INULL" skips loading the ISAMFIND.INI file.
  149.  
  150.  
  151. Format statements:
  152.  
  153. Within the ISAMFIND.INI file, you can specify two format strings, one for input
  154. and the second for output.  ISAMMAKE uses the input string to to read the input
  155. directory listings .  ISAMFIND uses the output string to determine how to
  156. display the file directory listings.
  157.  
  158. The format strings begin with "FI=" (for input format) or "FO=" (for output
  159. format) followed by string literals (like spaces) and information variables.
  160.  
  161. For ISAMMAKE, the default format is presumed to consist of a filename, followed
  162. by a file description.  In fact, ISAMMAKE can only process these fields (it
  163. ignores date, time, etc information).  So, for ISAMMAKE, the format statement
  164. defaults to:
  165.  
  166.         FI=%fname% %fdesc%
  167.  
  168.  
  169. For ISAMFIND, on the other hand, the program presumes you want a bit more
  170. information available such as %fdate% (file date) and %ftime% (file time).  The
  171. default format statement is:
  172.  
  173.         FO=%fratc% %fname(12)% %fdate(mm-dd-yy)% %fdesc(45)%
  174.  
  175. Format variables that are available are the following:
  176.  
  177.         %fpath%         the path of the file including drive
  178.         %fname%         the immediate file name for the file; a complete file
  179.                         name might require "%fpath%%fname%"
  180.         %fsize%         the size of the file in bytes
  181.         %fdate%         the creation date for the file
  182.         %ftime%         the creation time for the file in hh:mm format
  183.         %fdesc%         the file description
  184.         %fword%         the number of words in the document
  185.         %foccr%         the number of times your search word(s) appear
  186.         %frate%         the numerical rating of the file (see the ratings
  187.                         discussion in ISAMFIND.DOC)
  188.         %fratc%         the one-letter representation of the scoring of the
  189.                         file (see ISAMFIND.DOC for a discussion of scoring;
  190.                         characters used are .░▒▓█)
  191.         %fillr%         filler field (skip on input in ISAMMAKE; don't use at
  192.                         all in ISAMFIND)
  193.  
  194. Most of the variables can include a format specifier in parentheses before the
  195. second "%".  Typically, this indicates the number of spaces to allocate for the
  196. field.  For example, "%fsize(10)%" will show the file size in a 10-character
  197. field.
  198.  
  199. For file descriptions, the format specifier indicates the maximum number of
  200. letters of the description to print out.  If there is a continuation indicator
  201. (/CONT=string), the remainder of the description will print out on subsequent
  202. lines.
  203.  
  204. For the file date, the format specifier can be any combination of "mm" (month),
  205. "dd" (day), and "yy" (year) with separators.  For example, the default format
  206. specifier for date is "mm/dd/yy".  You can make this "yy-mm-dd" if you'd like
  207. by including "%date(yy-mm-dd)%" in your output format string.
  208.  
  209.  
  210.  
  211. Syntax:
  212.  
  213.     ISAMFIND [ string [ string ]... ] /Fcorename [ /2 | /3 | /4 | /5 ]
  214.       [ /READ | /Vpgm | /-READ ] [ /TOP=n ] [ /TRUNC | /-TRUNC ]
  215.       [ /ACCEPT=string ] [ /AREA=string ] [ /Xfilename ] [ /SINCE=yymmdd ]
  216.       [ /Ofilename | /-O ] [ /OVERWRITE | /-OVERWRITE | /OVERASK | /APPEND ]
  217.       [ /CONT=string ] [ /PATH | /-PATH ] [ /Iinitfile | /-I ] [ /? ]
  218.  
  219. where:
  220.  
  221. "string" is from one to ten words to search for.  For example,
  222.  
  223.         ISAMFIND IMPLICIT PRICE
  224.  
  225. The program automatically does an AND test on the words.  The searching is done
  226. exactly although case is ignored.  You can search for words that begin with a
  227. given string by ending the request with an asterisk.  For example:
  228.  
  229.         ISAMFIND PROD*
  230.  
  231. If no search string is provided, the routine will prompt you for one.
  232. Currently, the routine only allows up to 10 search strings to be entered.  You
  233. can include hexadecimal codes in your search string.
  234.  
  235. "/Fcorename" specifies the corename of the ISAM data base to list.  Should
  236. correspond to the name plugged into ISAMMAKE when the files are originally
  237. built.  (See ISAMMAKE.DOC for a description of the ISAM files.)
  238.  
  239. "/2", "/3", "/4", and "/5" specifies the minimum length word search allowed.
  240. The routine should use the same minimum specified when the ISAM files were built
  241. by ISAMMAKE.EXE.  By default, the minimum word length is 3.
  242.  
  243. "/READ" says to load the READ program and view the resulting C:\ISAMFIND.OUT
  244. file.  The file can be viewed outside of ISAMFIND later if you want.  Note that
  245. READ.EXE must exist in your path in order for this option to work.  You can use
  246. the /Vpgm option (with a path) if you have access to READ but it's not in your
  247. path.
  248.  
  249. "/Vpgm" says to load another text-viewing program (e.g. "/VLIST") instead of
  250. READ.EXE to view the file.  A path can be specified if necessary which is useful
  251. if the file viewer is not in your path.
  252.  
  253. "/-READ" says to skip loading the text-viewing program.  This is the default.
  254.  
  255. "/TOP=n" specifies that you want the top n-number of files to be shown.  Based
  256. on their relative scores, the documents are always shown in best to worst order.
  257. Initially, the default is "/TOP=15".  The maximum you can specify is "/TOP=100".
  258.  
  259.  
  260. "/TRUNC" says that all searches are to be, by default, only for exactly the
  261. word specified.  So "THE" will not find "THESE".  You can override any
  262. individual specification by including an asterisk after it ("THE*" will find
  263. "THESE" even if /TRUNC is specified).  Initially defaults to "/-TRUNC".
  264.  
  265. "/-TRUNC" says that all searches should presume any number of characters can
  266. follow the search characters specified.  So "THE" will find "THESE".  This is
  267. initially the default.
  268.  
  269. "/ACCEPT=string" allows you to specify characters *other than A to Z* that
  270. should be accepted as parts of words.  Foreign users, for example, might want to
  271. include some foreign characters.  The string can include hexadecimal codes.
  272.  
  273. "/AREA=string" restricts the output to words from those files that are in a
  274. specific file area as defined by the "/AREA=string" specification when the
  275. ISAMMAKE program is run or by the filename when /C=F is used by ISAMMAKE.
  276.  
  277. "/Xfilename" specifies that there are certain words you want excluded from
  278. consideration when the user enters them.  This file should be an ASCII text file
  279. with the words beginning in column 1.  The words can be in any order.  Remember
  280. that documents are retrieved which have every word the user enters.  If they
  281. enter something like "DOG AND CAT" and the word "AND" is not in a given
  282. document, the document will not show up in the final result.  A typical
  283. exclusion file might have all of the following common words in it:  AND, THE,
  284. FOR, BUT, NOT, etc.
  285.  
  286. "/SINCE=yymmdd" specifies that you only want documents that were created on the
  287. above date or afterward.  This is useful for cases where you only want recent
  288. documents to be retrieved.
  289.  
  290. "/Ofilename" sends the results to a file instead of to the screen.  This
  291. automatically invokes the /-READ option too.
  292.  
  293. "/-O" skips creating an output file with the results.  This option is mainly
  294. designed to allow you to override a specification in an INI file.
  295.  
  296. "/OVERWRITE" says to overwrite the output file if it exists already.
  297.  
  298. "/-OVERWRITE" says to abort if the output file exists already.
  299.  
  300. "/OVERASK" says to ask if the output file exists already.  This is initially
  301. the default.
  302.  
  303. "/APPEND" says to append (add) to the output file if it exists already.
  304.  
  305. "/CONT=string" says that lines whose descriptions should be continued on a
  306. second line due to length should have their continuations begin with a specific
  307. string.  Defaults to none.
  308.  
  309.  
  310. "/PATH" specifies that the original file paths are to be looked for when the
  311. file is looked for.  If the file cannot be found in the original path, it will
  312. be looked for in the default subdirectory on the default drive.  If it can't
  313. be found in either location, an error message will be shown.  This is initially
  314. the default.
  315.  
  316. "/-PATH" specifies that the file is to be looked for in the default subdirectory
  317. on the default drive only.  This is typically done if you've created the word
  318. index in one place and then copied all of the indexes and files to another drive
  319. for distribution.
  320.  
  321. "/Iinitfile" says to read an initialization file with the file name "initfile".
  322. The file specification *must* contain a period.  If no drive or path information
  323. is specified, the program will search for initfile beginning in your default
  324. subdirectory and then going throughout your DOS path.  The use of an
  325. initialization file is optional.  Initially defaults to "/IISAMFIND.INI".
  326.  
  327. "/-I" (or "/INULL") says to skip loading the initialization file.
  328.  
  329. "/?" or "/HELP" or "HELP" shows you the syntax for the command.
  330.  
  331.  
  332. Decimal and hexadecimal codes:
  333.   e.g. "\066\097\116" and "&H426174" both are "Bat"
  334. +---------------------------------------------------------------------------
  335. | dec  hex chr | dec  hex chr | dec  hex chr | dec  hex chr | dec  hex chr |
  336. +--------------+--------------+--------------+--------------+--------------+
  337. | \000 &H00 nul| \052 &H34 4  | \104 &H68 h  | \156 &H9C £  | \208 &HD0 ╨  |
  338. | \001 &H01   | \053 &H35 5  | \105 &H69 i  | \157 &H9D ¥  | \209 &HD1 ╤  |
  339. | \002 &H02   | \054 &H36 6  | \106 &H6A j  | \158 &H9E ₧  | \210 &HD2 ╥  |
  340. | \003 &H03   | \055 &H37 7  | \107 &H6B k  | \159 &H9F ƒ  | \211 &HD3 ╙  |
  341. | \004 &H04   | \056 &H38 8  | \108 &H6C l  | \160 &HA0 á  | \212 &HD4 ╘  |
  342. | \005 &H05   | \057 &H39 9  | \109 &H6D m  | \161 &HA1 í  | \213 &HD5 ╒  |
  343. | \006 &H06   | \058 &H3A :  | \110 &H6E n  | \162 &HA2 ó  | \214 &HD6 ╓  |
  344. | \007 &H07 bel| \059 &H3B ;  | \111 &H6F o  | \163 &HA3 ú  | \215 &HD7 ╫  |
  345. | \008 &H08 bs | \060 &H3C <  | \112 &H70 p  | \164 &HA4 ñ  | \216 &HD8 ╪  |
  346. | \009 &H09 tab| \061 &H3D =  | \113 &H71 q  | \165 &HA5 Ñ  | \217 &HD9 ┘  |
  347. | \010 &H0A lf | \062 &H3E >  | \114 &H72 r  | \166 &HA6 ª  | \218 &HDA ┌  |
  348. | \011 &H0B vt | \063 &H3F ?  | \115 &H73 s  | \167 &HA7 º  | \219 &HDB █  |
  349. | \012 &H0C pg | \064 &H40 @  | \116 &H74 t  | \168 &HA8 ¿  | \220 &HDC ▄  |
  350. | \013 &H0D cr | \065 &H41 A  | \117 &H75 u  | \169 &HA9 ⌐  | \221 &HDD ▌  |
  351. | \014 &H0E   | \066 &H42 B  | \118 &H76 v  | \170 &HAA ¬  | \222 &HDE ▐  |
  352. | \015 &H0F   | \067 &H43 C  | \119 &H77 w  | \171 &HAB ½  | \223 &HDF ▀  |
  353. | \016 &H10   | \068 &H44 D  | \120 &H78 x  | \172 &HAC ¼  | \224 &HE0 α  |
  354. | \017 &H11   | \069 &H45 E  | \121 &H79 y  | \173 &HAD ¡  | \225 &HE1 ß  |
  355. | \018 &H12   | \070 &H46 F  | \122 &H7A z  | \174 &HAE «  | \226 &HE2 Γ  |
  356. | \019 &H13   | \071 &H47 G  | \123 &H7B {  | \175 &HAF »  | \227 &HE3 π  |
  357. | \020 &H14   | \072 &H48 H  | \124 &H7C |  | \176 &HB0 ░  | \228 &HE4 Σ  |
  358. | \021 &H15   | \073 &H49 I  | \125 &H7D }  | \177 &HB1 ▒  | \229 &HE5 σ  |
  359. | \022 &H16   | \074 &H4A J  | \126 &H7E ~  | \178 &HB2 ▓  | \230 &HE6 µ  |
  360. | \023 &H17   | \075 &H4B K  | \127 &H7F   | \179 &HB3 │  | \231 &HE7 τ  |
  361. | \024 &H18   | \076 &H4C L  | \128 &H80 Ç  | \180 &HB4 ┤  | \232 &HE8 Φ  |
  362. | \025 &H19   | \077 &H4D M  | \129 &H81 ü  | \181 &HB5 ╡  | \233 &HE9 Θ  |
  363. | \026 &H1A eof| \078 &H4E N  | \130 &H82 é  | \182 &HB6 ╢  | \234 &HEA Ω  |
  364. | \027 &H1B esc| \079 &H4F O  | \131 &H83 â  | \183 &HB7 ╖  | \235 &HEB δ  |
  365. | \028 &H1C   | \080 &H50 P  | \132 &H84 ä  | \184 &HB8 ╕  | \236 &HEC ∞  |
  366. | \029 &H1D ???| \081 &H51 Q  | \133 &H85 à  | \185 &HB9 ╣  | \237 &HED φ  |
  367. | \030 &H1E ???| \082 &H52 R  | \134 &H86 å  | \186 &HBA ║  | \238 &HEE ε  |
  368. | \031 &H1F ???| \083 &H53 S  | \135 &H87 ç  | \187 &HBB ╗  | \239 &HEF ∩  |
  369. | \032 &H20    | \084 &H54 T  | \136 &H88 ê  | \188 &HBC ╝  | \240 &HF0 ≡  |
  370. | \033 &H21 !  | \085 &H55 U  | \137 &H89 ë  | \189 &HBD ╜  | \241 &HF1 ±  |
  371. | \034 &H22 "  | \086 &H56 V  | \138 &H8A è  | \190 &HBE ╛  | \242 &HF2 ≥  |
  372. | \035 &H23 #  | \087 &H57 W  | \139 &H8B ï  | \191 &HBF ┐  | \243 &HF3 ≤  |
  373. | \036 &H24 $  | \088 &H58 X  | \140 &H8C î  | \192 &HC0 └  | \244 &HF4 ⌠  |
  374. | \037 &H25 %  | \089 &H59 Y  | \141 &H8D ì  | \193 &HC1 ┴  | \245 &HF5 ⌡  |
  375. | \038 &H26 &  | \090 &H5A Z  | \142 &H8E Ä  | \194 &HC2 ┬  | \246 &HF6 ÷  |
  376. | \039 &H27 '  | \091 &H5B [  | \143 &H8F Å  | \195 &HC3 ├  | \247 &HF7 ≈  |
  377. | \040 &H28 (  | \092 &H5C \  | \144 &H90 É  | \196 &HC4 ─  | \248 &HF8 °  |
  378. | \041 &H29 )  | \093 &H5D ]  | \145 &H91 æ  | \197 &HC5 ┼  | \249 &HF9 ∙  |
  379. | \042 &H2A *  | \094 &H5E ^  | \146 &H92 Æ  | \198 &HC6 ╞  | \250 &HFA ·  |
  380. | \043 &H2B +  | \095 &H5F _  | \147 &H93 ô  | \199 &HC7 ╟  | \251 &HFB √  |
  381. | \044 &H2C ,  | \096 &H60 `  | \148 &H94 ö  | \200 &HC8 ╚  | \252 &HFC ⁿ  |
  382. | \045 &H2D -  | \097 &H61 a  | \149 &H95 ò  | \201 &HC9 ╔  | \253 &HFD ²  |
  383. | \046 &H2E .  | \098 &H62 b  | \150 &H96 û  | \202 &HCA ╩  | \254 &HFE ■  |
  384. | \047 &H2F /  | \099 &H63 c  | \151 &H97 ù  | \203 &HCB ╦  | \255 &HFF    |
  385. | \048 &H30 0  | \100 &H64 d  | \152 &H98 ÿ  | \204 &HCC ╠  |              |
  386. | \049 &H31 1  | \101 &H65 e  | \153 &H99 Ö  | \205 &HCD ═  |              |
  387. | \050 &H32 2  | \102 &H66 f  | \154 &H9A Ü  | \206 &HCE ╬  |              |
  388. | \051 &H33 3  | \103 &H67 g  | \155 &H9B ¢  | \207 &HCF ╧  |              |
  389. +--------------+--------------+--------------+--------------+--------------+
  390.